Inside Macintosh: QuickDraw GX Printing Extensions and Drivers /

Chapter 1 - Introduction to Printing Extensions and Drivers / About QuickDraw GX Printing Extensions and Printer Drivers

QuickDraw GX Printing and Messages

Printing with QuickDraw GX is based on a message-passing architecture. During
the printing process, certain printing-related tasks often need to be done, or certain printing-related conditions arise. QuickDraw GX sends a large number of messages to notify such programs as an application, printing extension, and printer driver about these tasks and conditions. These messages are called printing messages.

Your printing extension or printer driver might need to respond to these printing messages to make available its features or functionality. For example, your printing extension could respond to a particular printing message called GXDespoolPage to
add a date-time stamp to each printed page. Or your printer driver could respond to
the GXOpenConnection message to verify that the corresponding printing device is working properly. This response of intercepting a specific printing message and taking some action is called a message override, which is performed by an override function that you define in your extension or driver.

Before you learn more about how message overrides work, it's important to have an overview of what happens when QuickDraw GX sends a printing message. Because your printing extension or printer driver may respond to a printing message, it is called a message handler. A number of message handlers, including your extension or driver, an application, and QuickDraw GX itself, can respond to printing messages.

Each message handler is part of the message chain, which links the handlers in a hierarchical sequence. Each handler in the hierarchy receives the message and decides whether to respond to the message and whether to forward the message to the handler below it in the hierarchy. A message handler provides a function to respond to any message that the handler wants to act upon.

QuickDraw GX provides a function to handle each message that it sends. These functions are called the default implementations of the messages and are activated whenever a message is not completely handled by another message. When you provide a function to handle a message in your printing extension or printer driver, you implement an override function, which can add to or replace the actions provided by other handlers of the message.

The declaration of each override function must exactly match the declaration of the message that it is overriding. You can use any name that you want for the override function, but you must declare the same return value and parameter types as are used for the message declaration. For example, one of the printing messages is named GXCountPages and has the following declaration:

OSErr GXCountPages(gxSpoolFile aSpoolFile, long *numPages);

If you override this message, you need to declare your override function with a matching header. For example,

OSErr MyCountPages(gxSpoolFile myFile, long *numPages);

In most cases, when your printing extension or printer driver overrides a printing message, it performs some operations and forwards the message to the next handler
in the message chain. This is called a partial override. (A total override is when the message is not forwarded.) Although some of the default implementations of the printing messages provided by QuickDraw GX are empty and simply return, most of
the default implementations do provide significant functionality. In many cases, you must allow the default implementation of a message to provide its actions; otherwise,
a vital operation might be neglected, potentially resulting in serious errors.

A typical message chain, in which several handlers respond to and forward a message,
is shown in Figure 1-1.

Figure 1-1 A printing message chain

Each printing message is described in the chapter "Printing Messages" in this book.
Each description includes information about whether you must forward the message to allow the default implementation to provide its actions. Each description also specifies whether, for a partial override of a message, you need to forward the message before adding your own actions or after adding your own actions.

The timing of when you forward a message, relative to when you perform your actions in an override function, can result in significant differences. For example, if you are creating a printing extension that combines eight pages of a document into one page
of thumbnail sketches, you might override the GXCountPages message, which QuickDraw GX sends to count the pages in the spool file. You would forward this message to allow the default implementation to count the pages, and your override would then modify that value. On the other hand, if you are creating an extension that adds a confidential stamp to each page as it gets spooled, you might override the GXSpoolPage message. You would add your stamp to the page before forwarding
the message to the default implementation, which would spool the page to file.

QuickDraw GX also provides a number of printing functions that you can only call
from within the message overrides that you implement in your extension or driver. These functions perform a variety of operations, including

• displaying status information and the printing alert boxes to the user
• interfacing with the paper trays
• communicating imaging options between a driver and an application
• gracefully handling errors that arise during the processing of certain
  printing messages

The printing functions that you can call from within your message overrides are described in the chapter "Printing Functions for Message Overrides" in this book.

The message-passing architecture used for QuickDraw GX printing is supported by the Message Manager, which is a general-purpose software component of QuickDraw GX that you can use for message-passing in your own programs. The Message Manager
and the concepts and terminology of message-based programming are described in Inside Macintosh: QuickDraw GX Environment and Utilities.

Main | Page One | What's New | Apple Computer, Inc. | Find It | Contact Us | Help